home *** CD-ROM | disk | FTP | other *** search
/ PD ROM 1 / PD ROM Volume I - Macintosh Software from BMUG (1988).iso / Programming / Programming Tools / XCMDs / XCMD.HowToUse.doc < prev    next >
Encoding:
Text File  |  1987-08-12  |  10.1 KB  |  234 lines  |  [TEXT/ttxt]
  1. XCMD and XFCN: The Magic Hooks That Extend HyperTalk
  2.  
  3.     This documentation by Ted Kaehler, 1 August 1987
  4.     For HyperCard 1.0.  (Works with internal versions 1.0B9 and later.)
  5.     ©Apple Computer, Inc. 1987
  6.     All Rights Reserved.
  7.  
  8. Dan Winkler has created an interface that allows powerful new commands 
  9. to be added to HyperCard "in the field."  When a command in a script 
  10. cannot be found, HyperCard looks for a resource of type XCMD with 
  11. the same name as the unknown command.  Likewise, when a function cannot
  12. be found, HyperCard looks for a resource of type XFCN.  Whenever a handler 
  13. (for a command or function) is not found in a stack script, HyperCard
  14. immediately looks for a XCMD or XFCN in that stack.  The total 
  15. inheritance order is: Button (or Field), Card, Stack, stack XCMD, Home,
  16. home XCMD, XCMD in HyperCard application file, HyperCard command.  An 
  17. XCMD or XFCN is a code resource with no header bytes (just like a desk 
  18. accessory).  You can move them from file to file with ResEdit or with 
  19. any other resource moving tool.
  20.  
  21. The only thing passed into an XCMD or XFCN is a pointer to a XCmdBlock.  
  22. It looks like this:
  23.  
  24.   XCmdPtr = ^XCmdBlock;
  25.   XCmdBlock =
  26.     RECORD
  27.       paramCount:  INTEGER;                  { the number of arguments }
  28.       params:      ARRAY[1..16] OF Handle;   { the arguments }
  29.       returnValue: Handle;                   { the result of this XCMD }
  30.       passFlag:    BOOLEAN;                  { pass the message on? }
  31.  
  32.       entryPoint:  ProcPtr;                  { call back to HyperCard }
  33.       request:     INTEGER;                  { what you want to do }
  34.       result:      INTEGER;                  { the answer it gives }
  35.       inArgs:      ARRAY[1..8] OF LongInt;   { args XCMD sends HyperCard }
  36.       outArgs:     ARRAY[1..4] OF LongInt;   { answer HyperCard sends back }
  37.     END;
  38.  
  39. You read the arguments (they are handles to zero terminated strings), 
  40. do whatever the purpose of this XCMD is, and optionally store a 
  41. result into returnValue.  All data values going to and from HyperTalk 
  42. are zero-terminated ASCII strings.
  43.  
  44. Resources of type XCMD are commands, and resources of type XFCN are 
  45. functions that return a value.  If you store a result string into 
  46. returnValue in a command, the user can get it by asking for "the result"
  47. (useful for explaining why there was an error).  In a function, you are
  48. expected to store the answer into returnValue.  If you don't store 
  49. anything, the result is the empty string.
  50.  
  51. If passFlag is false (the normal case), this XCMD or XFCN has handled the 
  52. message and the script resumes execution.  If passFlag is true, HyperCard
  53. searches the remaining inheritance chain for another handler or
  54. XCMD with the same name.  This is just like the "pass" control structure
  55. in a script.
  56.  
  57. The file Flash.p is an example XCMD.  It takes one argument which is 
  58. the ASCII characters for a decimal integer.  It inverts the screen 
  59. twice the number of times indicated.  It is meant to be used as a command 
  60. and puts an error string into "the result" if the argument is odd.
  61.  
  62. Peek.p is a function (XFCN) that returns the value of any memory location 
  63. in the machine (purists avert your eyes).
  64.  
  65.  
  66. The second part of the XCmdBlock record has to do with 
  67. calling HyperCard back in the middle of your code to ask a question.
  68. If you wanted to manage the call to HyperCard yourself, you would 
  69. fill inArgs with your arguments, put a request code in request,
  70. and JSR to the address in entryPoint.  HyperCard returns the values you
  71. requested in outArgs and a result code in result.
  72.   
  73. However, Dan Winkler has packaged the entire range of calls on HyperCard,
  74. so that if you are using Pascal, you can simply call a procedure.  Both 
  75. Peek and Flash use some conversion routines that Dan has kindly
  76. supplied.  The file XCmdGlue.inc has the glue procedures.  Handle is always
  77. a handle to a zero-terminated string.  If a handle is returned, you are
  78. responsible for disposing it.  The calls are:
  79.  
  80. PROCEDURE SendCardMessage(msg: Str255);
  81. {  Send a HyperCard message (a command with arguments) to the current card. }
  82.  
  83. FUNCTION EvalExpr(expr: Str255): Handle;
  84. {  Evaluate a HyperCard expression and return the answer.  The answer is
  85.    a handle to a zero-terminated string. }
  86.  
  87. FUNCTION StringLength(strPtr: Ptr): LongInt;
  88. {  Count the characters from where strPtr points until the next zero byte. 
  89.    Does not count the zero itself.  strPtr must be a zero-terminated string.  }
  90.  
  91. FUNCTION StringMatch(pattern: Str255; target: Ptr): Ptr;
  92. { Perform case-insensitive match looking for pattern anywhere in
  93.   target, returning a pointer to first character of the first match,
  94.   in target or NIL if no match found.  pattern is a Pascal string,
  95.   and target is a zero-terminated string. }
  96.  
  97. PROCEDURE SendHCMessage(msg: Str255);
  98. {  Send a HyperCard message (a command with arguments) to HyperCard. }
  99.  
  100. PROCEDURE ZeroBytes(dstPtr: Ptr; longCount: LongInt);
  101. {  Write zeros into memory starting at dstPtr and going for longCount 
  102.    number of bytes. }
  103.  
  104. FUNCTION PasToZero(str: Str255): Handle;
  105. {  Convert a Pascal string to a zero-terminated string.  Returns a handle
  106.    to a new zero-terminated string.  The caller must dispose the handle. }
  107.  
  108. PROCEDURE ZeroToPas(zeroStr: Ptr; VAR pasStr: Str255);
  109. {  Fill the Pascal string with the contents of the zero-terminated
  110.    string.  You create the Pascal string and pass it in as a VAR 
  111.    parameter.  Useful for converting the arguments of any XCMD to 
  112.    Pascal strings.}
  113.  
  114. FUNCTION StrToLong(str: Str31): LongInt;
  115. {  Convert a string of ASCII decimal digits to an unsigned long integer. }
  116.  
  117. FUNCTION StrToNum(str: Str31): LongInt;
  118. {  Convert a string of ASCII decimal digits to a signed long integer.
  119.    Negative sign is allowed.  }
  120.  
  121. FUNCTION StrToBool(str: Str31): BOOLEAN;
  122. {  Convert the Pascal strings 'true' and 'false' to booleans. }
  123.  
  124. FUNCTION StrToExt(str: Str31): Extended;
  125. {  Convert a string of ASCII decimal digits to an extended long integer. }
  126. VAR x: Extended;
  127.  
  128. FUNCTION LongToStr(posNum: LongInt): Str31;
  129. {  Convert an unsigned long integer to a Pascal string.  }
  130.  
  131. FUNCTION NumToStr(num: LongInt): Str31;
  132. {  Convert a signed long integer to a Pascal string.  }
  133.  
  134. FUNCTION NumToHex(num: LongInt; nDigits: INTEGER): Str31;
  135. {  Convert an unsigned long integer to a hexadecimal number and put it
  136.    into a Pascal string.  }
  137.  
  138. FUNCTION BoolToStr(bool: BOOLEAN): Str31;
  139. {  Convert a boolean to 'true' or 'false'.  }
  140. VAR str: Str31;
  141.  
  142. FUNCTION ExtToStr(num: Extended): Str31;
  143. {  Convert an extended long integer to decimal digits in a string.  }
  144.  
  145. FUNCTION GetGlobal(globName: Str255): Handle;
  146. {  Return a handle to a zero-terminated string containing the value of 
  147.    the specified HyperTalk global variable.  }
  148.  
  149. PROCEDURE SetGlobal(globName: Str255; globValue: Handle);
  150. {  Set the value of the specified HyperTalk global variable to be
  151.    the zero-terminated string in globValue.  The contents of the 
  152.    Handle are copied, so you must still dispose it afterwards.  }
  153.  
  154. FUNCTION GetFieldByName(cardFieldFlag: BOOLEAN; fieldName: Str255): Handle;
  155. {  Return a handle to a zero-terminated string containing the value of 
  156.    field fieldName on the current card.  You must dispose the handle.
  157.    cardFieldFlag set to false indicates background, instead of card, field.  }
  158.  
  159. FUNCTION GetFieldByNum(cardFieldFlag: BOOLEAN; fieldNum: INTEGER): Handle;
  160. {  Return a handle to a zero-terminated string containing the value of 
  161.    field fieldNum on the current card.  You must dispose the handle.  }
  162.  
  163. FUNCTION GetFieldByID(cardFieldFlag: BOOLEAN; fieldID: INTEGER): Handle;
  164. {  Return a handle to a zero-terminated string containing the value of 
  165.    the field whise ID is fieldID.  You must dispose the handle.  }
  166.  
  167. PROCEDURE SetFieldByName(cardFieldFlag: BOOLEAN; fieldName: Str255; fieldVal: Handle);
  168. {  Set the value of field fieldName to be the zero-terminated string 
  169.    in fieldVal.  The contents of the Handle are copied, so you must 
  170.    still dispose it afterwards.  }
  171.  
  172. PROCEDURE SetFieldByNum(cardFieldFlag: BOOLEAN; fieldNum: INTEGER; fieldVal: Handle);
  173. {  Set the value of field fieldNum to be the zero-terminated string 
  174.    in fieldVal.  The contents of the Handle are copied, so you must 
  175.    still dispose it afterwards.  }
  176.  
  177. PROCEDURE SetFieldByID(cardFieldFlag: BOOLEAN; fieldID: INTEGER; fieldVal: Handle);
  178. {  Set the value of the field whose ID is fieldID to be the zero-
  179.    terminated string in fieldVal.  The contents of the Handle are 
  180.    copied, so you must still dispose it afterwards.  }
  181.  
  182. FUNCTION StringEqual(str1,str2: Str255): BOOLEAN;
  183. {  Return true if the two strings have the same characters.  
  184.    Case insensitive compare of the strings.  }
  185.  
  186. PROCEDURE ReturnToPas(zeroStr: Ptr; VAR pasStr: Str255);
  187. {  zeroStr points into a zero-terminated string.  Collect the 
  188.    characters from there to the next carriage Return and return 
  189.    them in the Pascal string pasStr.  If a Return is not found, 
  190.    collect chars until the end of the string. }
  191.  
  192. PROCEDURE ScanToReturn(VAR scanPtr: Ptr);
  193. {  Move the pointer scanPtr along a zero-terminated 
  194.    string until it points at a Return character
  195.    or a zero byte.  }
  196.  
  197. PROCEDURE ScanToZero(VAR scanPtr: Ptr);
  198. {  Move the pointer scanPtr along a zero-terminated 
  199.    string until it points at a zero byte.  }
  200.  
  201.  
  202.  
  203. Here are the files you will need:
  204.  
  205.  HyperXCmd.p
  206.  XCmdGlue.inc
  207.  Flash.p  (An example command to see how everything is really done.)
  208.  Peek.p   (An example function to see how everything is really done.)
  209.  
  210. Here are the typical MPW commands for compiling an XCMD
  211.  
  212.     pascal -w PioneerLVP4200.p
  213.     link -m ENTRYPOINT -o Video -rt XCMD=15 -sn Main=PioneerLVP4200 ∂
  214.       PioneerLVP4200.p.o "{MPW}"Libraries:interface.o
  215.  
  216. Video is the stack that MPW will install the XCMD in.  If you don't use 
  217. any of the routines in interface.o, its just
  218.  
  219.     pascal Flash.p
  220.     link -o HyperCommands -rt XCMD=0 -sn Main=Flash Flash.p.o
  221.  
  222. After executing these, use ResEdit to move the XCMD or XFCN to the 
  223. proper stack.
  224.  
  225. For "C" programmers, the author has provided a defintion (HyperXCmd.h) and
  226. an include file (XCmdGlue.inc.c) and an example (CFlash.c).
  227.  
  228. Breakpoints do not appear to work in XCMDs, but putting a debugger call
  229. in your code does work.  In addition, saying:
  230.  
  231.    hd 'h'
  232.  
  233. in MacsBug allows you to find your resource in memory by seeing its name
  234. and location in the listing.